home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / gl_dev.idb / usr / share / src / OpenGL / tools / toogl / README.z / README
Encoding:
Text File  |  1996-03-15  |  4.9 KB  |  189 lines
  1.  
  2. Toogl (TO OpenGL) is a program to translate Iris GL programs into OpenGL
  3. programs.
  4.  
  5. Usage: toogl [-clLqwv] < infile > outfile
  6.         -c  don't put comments with OGLXXX into program
  7.         -l  don't translate lighting calls (e.g. lmdef, lmbind, #defines) 
  8.         -L  translate lighting calls for emulation library (mylmdef, mylmbind) (implies -l) 
  9.         -q  don't translate event queue calls (e.g. qread, setvaluator) 
  10.         -v  print revision number.
  11.         -w  don't translate window manager calls (e.g. winopen, mapcolor) 
  12.  
  13. Typical usage might be like this:
  14.  
  15. #!/bin/sh
  16. mkdir OpenGL
  17. for i in *.c
  18.     do
  19.     echo $i
  20.     toogl < $i > OpenGL/$i
  21.     done
  22.  
  23. You should most definitly KEEP YOUR ORIGINAL SOURCE. Use a directory
  24. like the above shell script or use RCS:
  25.  
  26. #!/bin/sh
  27. for i in *.c
  28.     do
  29.     ci -fm"check in for toogl" $i < /dev/null
  30.     co -lp $i | toogl  > $i
  31.     done
  32.  
  33.  
  34. That's it. It's a filter that scans each line of infile looking for
  35. IrisGL stuff. When it finds an IrisGL function, it replaces it with the
  36. corresponding OpenGL function(s). It attempts to fix up arguments where
  37. it can. Many IrisGL #defines from gl.h are also translated into
  38. equivalent OpenGL defines where possible. You will need to edit the
  39. results and probably use gdiff to figure things out.
  40.  
  41. Any time toogl does something that I thought you might need to look at,
  42. check, or change, it outputs a comment with "OGLXXX" in it. These come
  43. out before the line in question and you may search for them with your
  44. editor.  Use the -c option if you don't want the comments.
  45.  
  46. Toogl can help with translation of lighting commands (lmdef, lmbind,
  47. and data structures), but it's not perfect. The -L option will cause
  48. toogl to translate lmdef and lmbind into commands for the emulation
  49. library in irisgl_light.c
  50.  
  51. Toogl goes wild on sections of code where you make window manager,
  52. window configuration, device, and event calls. You're going to have to
  53. re-write these yourself until some compatibility library comes along.
  54. Using the -w and -q options will leave this code alone so you can still
  55. read it to translate it manually.
  56.  
  57. Toogl understands a little about matching parentheses and quotes:
  58.  
  59.     v3f( v[strlen(strcat(foo, "foo("))] );
  60.  
  61.  
  62. translates into:
  63.  
  64.         glVertex3fv( v[strlen(strcat(foo, "foo("))] );
  65.       
  66.  
  67. PROBLEMS:
  68.  
  69. 1) Toogl expects to find the matching parentheses or quotes ON THE SAME LINE
  70. as the IrisGL function:
  71.  
  72.     v3f( foo 
  73.         ); 
  74.  
  75. won't work. This will probably generate an warning message and the function
  76. won't be changed.
  77.  
  78.  
  79. 2) Toogl expects to find only <space> and <tab> characters between the 
  80. function name and the '(':
  81.  
  82.     v3f
  83.         (foo);
  84.  
  85. will be left un-changed, as will:
  86.  
  87.     v3f /* comment */ (foo);
  88.  
  89.  
  90. 3) C comments inside the argument list of a function shouldn't contain 
  91. parentheses or quote characters. e.g:
  92.  
  93.     v3f ( foo /* I really mean bar "-) */ );
  94.  
  95. will generate a warning and be un-changed.
  96.  
  97.  
  98. 4) "Gets" in IrisGL were of the form:
  99.  
  100.  
  101.     int getthing();
  102.  
  103.     int getthings( int *a, int *b);
  104.  
  105. and y'all write code like:
  106.  
  107.     thing = getthing();
  108.  
  109.     if(getthing() == THING) {
  110.     }
  111.  
  112.     getthings (&a, &b);
  113.  
  114. "Gets" in OpenGL are of the form:
  115.  
  116.     void glGetIntegerfv(NAME_OF_THING, &thing);
  117.  
  118. Toogl does the best it can:
  119.  
  120.     i = getcolor();
  121.  
  122.     getdepth(&near, &far);
  123.  
  124. will translate into:
  125.  
  126.  
  127.     /* OGLXXX
  128.      * getshade:
  129.      * GLint gctmp;
  130.      */
  131.     i = (glGetIntegerv(GL_CURRENT_INDEX, &gstmp), gstmp);
  132.  
  133.     /* OGLXXX You can probably do better than this. */
  134.     {
  135.         int    get_depth_tmp[2];
  136.         glGetIntegerv(GL_DEPTH_RANGE, get_depth_tmp);
  137.         *(&near) = get_depth_tmp[0];
  138.         *( &far) = get_depth_tmp[1];
  139.     };
  140.  
  141.  
  142. 5) "lmdef" and "texdef" are close to impossible to deal with. The parameter lists
  143. are translated and commented and the function calls are mangled. See the
  144. -l and -L options for lighting. No such code currently exists for texture.
  145.  
  146. 6) Toogl does all the translation on ONE LINE. I've re-formatted the stuff above
  147. to make it readable. The comments do come out as shown. You may want to use cb.
  148. If you do, you may want to "cb" your code before using toogl, so gdiff
  149. will only show changes due to toogl and not ones due to cb. Note that cb 
  150. isn't perfect, either.
  151.  
  152. 7) This space intentionally left almost blank.
  153.  
  154. 8) (BUG) stuff inside quotes and comments is scanned, too.
  155.  
  156.     printf("scale (reason %d)", reason); 
  157.  
  158. causes a non-fatal error message. (Looks like a call to scale with one argument).
  159.  
  160. 9) You'll need to change #include <gl.h> into #include <GL/gl.h>
  161. This sed script may be of help:
  162.  
  163. sed -e 's@^#[   ]*include[       ]*[<"][^">]*[/]*gl.h[">]@#include "GL/gl.h"@' < in  > out
  164.               ^^ tab       ^^ tab
  165.  
  166. 10) There are 2 warning messages during compilation: optimization won't
  167. help the routines that are too big. 
  168.  
  169. 11) (BUG) toogl translates stuff in comments and likely screws up the comment 
  170. in the process:
  171.  
  172.  
  173.     /* 
  174.      i = getcolor(); 
  175.      */
  176.  
  177.  
  178. (incorrectly) translates into:
  179.  
  180.  
  181.         /* 
  182.         /* OGLXXX
  183.          * getshade:
  184.          * GLint gctmp;
  185.          */
  186.          i = (glGetIntegerv(GL_CURRENT_INDEX, &gstmp), gstmp); 
  187.          */
  188.  
  189.